.. _辅助工具使用教程:
************************************
辅助工具使用教程
************************************



.. _环境部署:

==============================================================================
env环境部署
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

依赖环境: **Python3.6及以上**
 
- 依赖库安装：
 (1) **Pymatgen库** ：使用 ``pip install pymatgen`` 安装；
 (2) **Statsmodels库** ：使用 ``pip install statsmodels`` 安装；
 (3) **Dspawpy库** ：使用 ``pip install -i https://test.pypi.org/simple/ dspawpy==0.3.0`` 安装；


.. _ 电荷密度数据处理:

==============================================================================
rho电荷密度数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

DS-PAW使用 *pymatgen* 的画图程序来显示的二维数据，使用 *VESTA* 来显示三维数据。以应用教程中Si体系的 ``band.json`` 和 ``dos.json`` 为例子：

(1) 在计算目录中新建一个 :guilabel:`trans_rho.py` 文件，内容如下：

.. code-block:: python
    :linenos:

     import json
     from dspawpy.io import write_VESTA_format

     with open("./rho.json","r") as file:
     rho = json.load(file)

     write_VESTA_format(rho["AtomInfo"], [rho["Rho"]["TotalCharge"]], "DS-PAW-rho.vesta")

- 第1，2行为需要导入的 **python** 库函数；
- 第4，5行为需要读取的 ``json`` 文件；
- 第7行为执行 :guilabel:`write_VESTA_format` 函数，将数据保存为VESTA可识别的格式，其中 **rho["AtomInfo"]** 为读取 ``rho.json`` 中的晶格及坐标信息,  **[rho["Rho"]["TotalCharge"]]** 为 ``rho.json`` 中总的电荷密度的三维数据, ``DS-PAW-rho.vesta`` 表示生成的 **vesta** 格式数据；

(2) 执行 :guilabel:`python trans_rho.py` ；
(3) 得到转换后的文件 ``DS-PAW-rho.vesta`` ，将其重命名为 ``CHGCAR.vasp`` 以便在 **VESTA** 显示；
(4) 将 ``CHGCAR.vasp`` 文件拖入VESTA中则可得到如下的电荷密度图

.. figure:: images/1-3.png


.. _ 能带数据处理:

==============================================================================
band能带数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以不开自旋时的MoS2体系的 ``band.json`` 为例子：

（1） **普通能带处理** ：

创建 :guilabel:`bandplot.py` 文件，具体代码如下：

.. code-block:: python
    :linenos:

    from pymatgen.electronic_structure.plotter import BSPlotter
    from dspawpy.io import get_band_data

    band_data = get_band_data("./band.json")

    bsp = BSPlotter(bs=band_data)
    plt = bsp.get_plot()
    plt.savefig("bandplot.png",img_format="png")
    plt.show()


- 第1、2行为需要导入的 **python** 库函数，这里用到了pymatgen中的 **BSPloter** 库，以及 :guilabel:`dspawpy.io` 中的 ``get_band_data`` 函数；
- 第4行为读取 ``band.json`` 文件构造 **band_data** 这个结构体；
- 第6行为调用BSPloter处理 **band_data** 数据；
- 第7行为使用 ``bsp`` 下面的 **get_plot** 进行画图；
- 第8行为保存图片的名称和格式，将数据保存为png格式命名为 **bandplot.png** ；
- 第9行为显示图片，如果用户运行的环境无法直接显示图片，用户可以将该行注释，之后打开 **bandplot.png** 文件查看。

(2) 执行 :guilabel:`python bandplot.py`
(3) 生成 ``bandplot.png`` 文件


.. admonition:: 知识点：

    1. `Pymatgen中主要用到 electronic_structure.plotter 模块，基本上该模块下的80%的功能都能使用；`
    2. `dspawpy.io 模块为 DS-PAW 的接口模块；`
    3. `使用 get_band_data 函数可以将 DS-PAW 计算得到的 band.json 文件转化为 pymatgen 支持的格式；`
    4. `使用 BSPlotter 模块获取到 DS-PAW 计算的 band.json 的数据；`
    5. `使用 BSPlotter 模块中 get_plot 函数绘制能带图；`
    6. `使用 savefig 函数可以将能带图以不同格式保存；`
    7. `使用 show 函数能够直接显示能带图，如果用户的机器上不支持图形界面，可以用#注释 show函数；`

执行代码可以得到以下能带图：

.. figure:: images/4-1.png

（2） **将能带投影到每一种元素然后分别作图，通过线条的粗细来表示该元素对该轨道的贡献** ：

创建 :guilabel:`bandplot_elt_projected.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from pymatgen.electronic_structure.plotter import BSPlotterProjected
  from dspawpy.io import get_band_data

  band_data = get_band_data("./band.json")

  # 构建投影band数据实例
  bsp = BSPlotterProjected(bs=band_data)
  # 绘制按元素投影图片,返回matplotlib.pyplot
  plt = bsp.get_elt_projected_plots()
  plt.savefig("bandplot_elt_projected.png",img_format="png")
  plt.show()

.. admonition:: 知识点：

    1.  `用户如果需要绘制能带投影的数据，此时需要使用 BSPlotterProjected模块；`
    2.  `使用 BSPlotterProjected模块中 get_elt_projected_plots 函数能够绘制每种元素对轨道贡献的能带图；`

执行代码可以得到以下能带图：

.. figure:: images/4-2.png

（3） **将能带投影到每一种元素然后分别作图，通过不同的颜色来表示该元素对该轨道的贡献：**

创建 :guilabel:`bandplot_elt_projected_color.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from pymatgen.electronic_structure.plotter import BSPlotterProjected
  from dspawpy.io import get_band_data

  band_data = get_band_data("./data/band.json")

  bsp = BSPlotterProjected(bs=band_data)
  # 绘制投影到元素band图片,返回matplotlib.pyplot({'Mo':['d'],'S':['s']})
  plt = bsp.get_elt_projected_plots_color()
  plt.savefig("bandplot_elt_projected_color.png",img_format="png")
  plt.show()

.. admonition:: 知识点：

    `使用 BSPlotterProjected模块中 bandplot_elt_projected_color 函数能够绘制每种元素对轨道贡献的能带图，用红绿蓝三原色来表示 spd轨道；`

执行代码可以得到以下能带图：

.. figure:: images/4-3.png

（4） **能带投影到不同元素的不同轨道（L）：**

创建 :guilabel:`bandplot_projected.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from pymatgen.electronic_structure.plotter import BSPlotterProjected
  from dspawpy.io import get_band_data

  band_data = get_band_data("./data/band.json")

  bsp = BSPlotterProjected(bs=band_data)

  # 绘制投影到元素某些轨道band，返回matplotlib.pyplot
  plt = bsp.get_projected_plots_dots({'Mo':['d'],'S':['s']})
  plt.savefig("bandplot_projected.png",img_format="png")
  plt.show()

.. admonition:: 知识点：

   1. `使用 BSPlotterProjected模块中 get_projected_plots_dots可以让用户来自定义需要绘制的某种元素某种轨道(L)的能带图；`
   2. `例如 get_projected_plots_dots ({'Mo':['d'],'S':['s']})就是绘制Mo的d轨道和S的s轨道；`

执行代码可以得到以下能带图：

.. figure:: images/4-4.png

（5） **将能带投影到不同原子的不同轨道(M)：**

创建 :guilabel:`bandplot_plots_dots_patom_pmorb.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from pymatgen.electronic_structure.plotter import BSPlotterProjected
  from dspawpy.io import get_band_data

  band_data = get_band_data("./band.json")
  bsp = BSPlotterProjected(bs=band_data)

  plt = bsp.get_projected_plots_dots_patom_pmorb(dictio={'Mo':['px','py','pz']}, dictpa={'Mo':[1]})

  plt.savefig("bandplot_projected_plots_dots_patom_pmorb.png",img_format="png")
  plt.show()

- 第1、2行为需要导入的 **python** 库函数，这里用到了pymatgen中的 **BSPloter** 库，以及 :guilabel:`dspawpy.io` 中的 ``get_band_data`` 函数；
- 第4行为读取 ``band.json`` 文件构造 **band_data** 这个结构体；
- 第5行为调用 **BSPlotterProjected** 处理 **band_data** 数据；
- 第7行为使用 ``bsp`` 下面的 **get_projected_plots_dots** 进行画图，用户可以根据自己的体系和需要绘制的投影轨道对参数进行修改；
- 第9行为保存图片的名称和格式，这里将数据保存为png格式命名为 **bandplot_projected_plots_dots_patom_pmorb.png** ；
- 第10行为显示图片，如果用户运行的环境无法直接显示图片，用户可以将该行注释，之后打开 **png** 文件查看。



.. admonition:: 知识点：

    1.  `使用 BSPlotterProjected模块中 get_projected_plots_dots_patom_pmorb 的自由度更高，可以让用户来自定义需要绘制的某种原子某种轨道 (M) 的能带图；`
    2.  `dictpa指定原子，dictio 指定该原子的轨道；`
    3.  `get_projected_plots_dots_patom_pmorb函数中还可以使用 sum_atoms 功能将多个原子的贡献相加，该功能用户可以自行根据使用方法进行尝试；`

**注意：get_projected_plots_dots_patom_pmorb函数中序号是从1开始的；**

执行代码可以得到以下能带图：

.. figure:: images/4-5.png




.. _ 态密度数据处理:

==============================================================================
dos态密度数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以应用教程中的反铁磁NiO体系的 ``dos.json`` 为例子：

（1） **总的态密度** ：

创建 :guilabel:`dosplot_total.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from pymatgen.electronic_structure.plotter import DosPlotter
  from dspawpy.io import get_dos_data

  dos_data = get_dos_data("dos.json")
  dos_plotter = DosPlotter(stack=False,zero_at_efermi=True)
  dos_plotter.add_dos('total dos',dos=dos_data)

  plt = dos_plotter.get_plot()
  plt.savefig("dos_total.png",img_format="png")
  plt.show()

- 第1、2行为需要导入的 **python** 库函数，这里用到了pymatgen中的 **BSPloter** 库，以及 ``dspawpy.io`` 中的 ``get_dos_data`` 函数；
- 第4行为读取 ``dos.json`` 文件构造 **dos_data** 这个结构体；
- 第5行为调用 ``DosPlotter`` 处理 **dos_data** 数据，括号中 **stack=False** 表示态密度作图方式为曲线， **stack=True** 表示作图方式为面积， **zero_at_efermi** 控制是否将零点设为费米能级；
- 第6行使用 ``add_dos`` 来定义要处理的对象 **dos** ，调用前边定义好的dos对象 ``dos_data``
- 第8行使用 ``dos_plotter`` 下面的 get_plot 进行画图；
- 第9行为保存图片的名称和格式，这里将数据保存为png格式命名为 **dos_total.png** ；
- 第10行为显示图片，如果用户运行的环境无法直接显示图片，用户可以将第该行注释，之后打开 **png** 文件查看。


.. admonition:: 知识点：

    1.  `使用 get_dos_data 函数可以将DS-PAW计算得到的 dos.json 文件转化为 pymatgen 支持的格式；`
    2.  `使用 DosPlotter模块获取到DS-PAW计算的 dos.sjon 的数据；`
    3.  `DosPlotter函数可以传递参数：stack参数表示画态密度是否加阴影， zero_at_efermi 表示是否在态密度图中进行将费米能量置零，这里设置 stack=False , zero_at_efermi=False ；`
    4.  `使用 DosPlotter 模块中 add_dos 获取态密度的数据；`
    5.  `DosPlotter模块中 et_plot函数 绘制态密度图；`

执行代码可以得到以下态密度图：

.. figure:: images/4-6.png

（2） **将态密度投影到不同的轨道上(L)：**

创建 :guilabel:`dosplot_spd.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from pymatgen.electronic_structure.plotter import DosPlotter
  from dspawpy.io import get_dos_data

  dos_data = get_dos_data("dos.json")
  dos_plotter = DosPlotter(stack=False,zero_at_efermi=True)
  dos_plotter.add_dos_dict(dos_data.get_spd_dos())

  plt = dos_plotter.get_plot()
  plt.savefig("dos_spd.png",img_format="png")
  plt.show()


- 第1、2行是导入需要的 **python** 库函数，这里用到了 **pymatgen** 中的 **DosPlotter** 库，以及 :guilabel:`dspawpy.io` 中的 ``get_dos_data`` 函数；
- 第4行为读取 ``dos.json`` 文件构造 **dos_data** 这个结构体；
- 第5行为调用BSPlotterProjected处理 **dos_data** 数据，括号中 **stack=False** 表示态密度作图方式为曲线， **stack=True** 表示作图方式为面积， **zero_at_efermi** 控制是否将零点设为费米能级；
- 第6行使用 ``add_dos_dict`` 获取投影信息，对 ``dos_data`` 进行 :guilabel:`get_spd_dos` 操作，获得投影到轨道的信息；
- 第7行为保存图片的名称和格式，这里将数据保存为png格式命名为 **dos_spd.png** ；
- 第8行为显示图片，如果用户运行的环境无法直接显示图片，用户可以将该行注释，之后打开 **dos_spd.png** 文件查看。



.. admonition:: 知识点：

    1. `使用 DosPlotter模块中 add_dos_dict 函数 获取投影态密度的数据，之后使用 get_spd_dos 将投影信息按照 spd 轨道投影输出；`

执行代码可以得到以下态密度图：

.. figure:: images/4-7.png

（3） **将态密度投影到不同的元素上** ：

创建 :guilabel:`dosplot_element.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  # 导入pymatgen DosPlotter模块
  from pymatgen.electronic_structure.plotter import DosPlotter
  # 导入读取DS-PAW dos.json数据模块
  from dspawpy.io import get_dos_data


  dos_data = get_dos_data("dos.json")
  dos_plotter = DosPlotter(stack=False,zero_at_efermi=True)

  #按元素添加dos
  dos_plotter.add_dos_dict(dos_data.get_element_dos())

  #返回matplotlib.pyplot
  plt = dos_plotter.get_plot()
  plt.savefig("dos_element.png",img_format="png")
  plt.show()

.. admonition:: 知识点：

    1. `使用 DosPlotter模块中 add_dos_dict 函数 获取投影态密度的数据，之后使用 get_element_dos 将投影信息按照不同元素投影输出；`


执行代码可以得到以下态密度图：

.. figure:: images/4-8.png

（4） **将态密度投影到不同的元素的不同轨道(M)上：**

创建 :guilabel:`dosplot_element_orbital.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from pymatgen.electronic_structure.plotter import DosPlotter
  from pymatgen.electronic_structure.core import Orbital
  from dspawpy.io import get_dos_data

  dos_data = get_dos_data("dos.json")
  dos_plotter = DosPlotter(stack=False,zero_at_efermi=False)
  dos_plotter.add_dos("Ni dxy",dos_data.get_site_orbital_dos(dos_data.structure[0],Orbital(4)))
  #dos_plotter.save_plot("dos_element_orbital.png",img_format="png")
  dos_plotter.show()


.. admonition:: 知识点：

    1. `使用 get_site_orbital_dos函数 提取dos数据中特定原子，特定轨道的贡献，这是获取第2个原子的第5个轨道的态密度 dos_data.structure[0],Orbital(4)` ；
    2. `之后使用 DosPlotter模块中 add_dos函数 进行画图；`

**注意：get_site_orbital_dos函数中序号是从0开始的；**

执行代码可以得到以下态密度图：

.. figure:: images/4-9.png

（5） 将态密度投影到不同的原子的t2g轨道和eg轨道上：

以应用案例NiO的反铁磁计算得到的 ``dos.json`` 为例，

创建 :guilabel:`dosplot_t2g_eg.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from pymatgen.electronic_structure.plotter import DosPlotter
  from dspawpy.io import get_dos_data

  dos_data = get_dos_data("./dos.json")
  dos_plotter = DosPlotter(stack=False,zero_at_efermi=True)
  dos_plotter.add_dos_dict(dos_data.get_site_t2g_eg_resolved_dos(dos_data.structure[1]))
  dos_plotter.save_plot("dos_t2g_eg.png",img_format="png")
  dos_plotter.show()


- 第1，2行为需要导入的 **python** 库函数，这里用到了pymatgen中的 **DosPlotter** 库，以及我们自己写的 ``dspawpy.io`` 中的 :guilabel:`get_dos_data` 函数；
- 第4行为读取 ``dos.json`` 文件构造 ``dos_data`` 结构体；
- 第5行为调用DosPlotter处理dos_data数据，括号中 **stack=False** 表示态密度作图方式为曲线， **stack=True** 表示作图方式为面积， :guilabel:`zero_at_efermi` 控制是否将零点设为 **费米能级** ；
- 第6行使用 :guilabel:`add_dos_dict` 获取 **投影信息** ，对dos_data进行 :guilabel:`get_site_t2g_eg_resolved_dos` 操作，获得 **投影到轨道** 的信息；
- 第7行为保存图片的名称和格式，这里将数据保存为png格式命名为 **dos_t2g_eg.png** ；
- 第8行为显示图片，如果用户运行的环境无法直接显示图片，用户可以将该行注释了，之后打开 **dos_t2g_eg.png** 文件查看。

(2) 执行 :Guilabel:`python dosplot_t2g_eg.py` ；
(3) 生成 ``dos_t2g_eg.png`` 文件

.. figure:: images/phase3/NiO-dos.png


.. admonition:: 知识点：

    1. `使用 get_site_t2g_eg_resolved_dos函数 提取dos数据中特定原子的 t2g和 eg轨道的贡献，这是获取第1个原子的t2g和eg轨道的贡献；`
    2. `之后使用 DosPlotter 模块中 add_dos_dict函数 进行画图；`


.. _ 能带和态密度共同显示:

==============================================================================
bandDos能带和态密度共同显示
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以应用教程中Si体系的 ``band.json`` 和 ``dos.json`` 为例子：

（1） **将能带和态密度显示在一张图上：**

创建 :guilabel:`banddosplot.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  # 导入pymatgen BSDOSPlotter 画图模块
  from pymatgen.electronic_structure.plotter import BSDOSPlotter
  # 导入dspawpy 读取DS-PAW band.json,dos.json模块
  from dspawpy.io import get_band_data,get_dos_data

  # 读取dos.json, 参数dos.json文件路径
  dos_data = get_dos_data("./data/dos.json")
  # 读取band.json, 参数band.json文件路径
  band_data = get_band_data("./data/band.json")

  bdp = BSDOSPlotter()

  # 绘制BandDos图，返回matplotlib.pyplot
  plt = bdp.get_plot(bs=band_data,dos=dos_data)

  # 保存png图片
  plt.savefig("banddos.png",img_format="png")
  # 显示图片
  plt.show()

.. admonition:: 知识点：

    1. `首先使用 dspawpy.io 中的 get_band_data 和 get_dos_data 模块获取 band.json 和 dos.json 的数据；`
    2. `之后使用 BSDOSPlotter模块中的 get_plots函数 直接进行画图；`
    3. `如果需要将投影能带和投影态密度画在一起，可以参考前面单独画图的代码。`

执行代码可以得到以下能带态密度图：

.. figure:: images/4-11.png

.. _ 势函数数据处理:

==============================================================================
potential势函数数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以Si的slab模型的 ``potential.json`` 为例：

（1） **势函数转化为VESTA能够支持的三维显示格式**：

创建 :guilabel:`trans_VESTA.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

   import json
   from dspawpy.io import write_VESTA_format

   with open("./potential.json","r") as file:
         potential= json.load(file)

   write_VESTA_format(potential["AtomInfo"], [potential["Potential"]["TotalElectrostaticPotential"], potential["Potential"]], "DS-PAW.vesta")

- 第1，2行为需要导入的 **python** 库函数；
- 第4，5行为需要读取的 **json** 文件，这里 ``./potential.json`` 指的时读取当前路径下的 ``potential.json`` ，如果需要读取其他的 *json** 文件可以自行修改；
- 第6行为执行 :guilabel:`write_VESTA_format` 函数，将数据保存为 **VESTA** 可识别的格式，其中 ``potential["AtomInfo"]`` 为读取 ``potential.json`` 中的晶格及坐标信息,  **potential["Potential"]["TotalElectrostaticPotential"]** 为 ``potential.json`` 中总的静电势的三维数据,  **"DS-PAW- potential.vesta"** 表示将这些数据写入到 :guilabel:`DS-PAW- potential.vesta` 文件中；




**VESTA展现的效果可以通过设置VESTA中Isosurface level数值来调节，具体步骤为VESTA-properties-Isosurfaces-Isosurface level**



.. admonition:: 知识点：

    1. `使用 with open语法 加载需要处理的三维网格数据；`
    2. `使用 write_VESTA_format函数 可以将三维数据保存为VESTA格式的数据，其中 potential["AtomInfo"] 为晶格信息， potential["Potential"]["TotalElectrostaticPotential"] 总的静电势的数据，之后将数据命名为 DS-PAW.vesta ；`
    3. `write_VESTA_format 支持输出多个网格数据，例如想要保存总的和自旋静电势，命令如下：write_VESTA_format(potential["AtomInfo"], [potential["Potential"]["TotalElectrostaticPotential"], potential["Potential"]["SpinElectrostaticPotential"]], " DS-PAW.vesta ") ；`
    4. `处理部分电荷密度文件pcharge.json时，最后一行代码应可参考write_VESTA_format(pcharge["AtomInfo"], [pcharge["Pcharge"][0]["TotalCharge"]], "DS-PAW-pcharge.vesta")格式，其中[0]对应json文件中第1条待测能带电荷密度的三维数据，若需处理第2条能带该关键词应写作[1]。`



执行代码可以得到VESTA支持的数据，将数据拽入VESTA中得到以下势函数三维图：

.. figure:: images/4-12.png

（2） **将三维势函数进行面内平均：**

创建 :guilabel:`plot _planar_macroscopic.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  import json
  import numpy as np
  from dspawpy.plot import plot_potential_along_axis

  with open("./potential.json","r") as file:
      potential = json.load(file)

  grid = potential["AtomInfo"]["Grid"]
  pot= np.asarray(potential ["Potential"]["TotalElectrostaticPotential"]).reshape(grid,order="F")

  plt = plot_potential_along_axis(pot,axis=2,smooth=False)
  plt.legend()
  plt.show()

- 第1，2，3行为需要导入的 **python** 库函数，这里用到了 :guilabel:`dspawpy.io` 中的 ``plot_potential_along_axis`` 函数；
- 第5，6行为需要读取的 **json** 文件，这里 ``./potential.json`` 指的时读取当前路径下的 ``potential.json`` ，如果需要读取其他的 **json** 文件可以自行修改；
- 第8行为获取grid，其中 **potential["AtomInfo"]["Grid"]** 为读取 ``potential.json`` 中的晶格及坐标信息;
- 第9行为执行 :guilabel:`pot` 函数，其中 **potential["Potential"]["TotalLocalPotential"]** 为读取 ``potential.json`` 中的局部势能信息,
- 第11行调用 :guilabel:`plot_potential_along_axis` 函数作图， **smooth=False** 则不作宏观平均图；
- 第12行为设置图例；
- 第13行为显示图片



.. admonition:: 知识点：

    1. `进行面内平均及宏观平均时需要使用到 numpy 的库；`
    2. `DS-PAW软件中三维的数据都是按照一维的格式保存的，因此需要使用 np.asarray函数 将一维数据还原成3维数据；`
    3. `之后使用 plot_potential_along_axis 将某两个维度进行求平均，之后将剩下的维度数据进行绘图；`
    4. `plot_potential_along_axis的第一个变量为三维格点数据，第二个为沿着某个维度画图，将另外两个维度求平均，第三个参数为是否绘制宏观平均的曲线，第四个参数为宏观平均算法中的权重；`


执行代码可以得到以下势函数图：

.. figure:: images/4-13.png


.. _ 电子局域密度数据处理:

==============================================================================
elf电子局域密度数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以快速入门Si电子局域密度计算计算得到的 ``elf.json`` 为例：

(1) 在计算目录中新建一个 :guilabel:`trans_elf.py` 文件，内容如下：

.. code-block:: python
  :linenos:

   import json
   from dspawpy.io import write_VESTA_format

   with open("./elf.json","r") as file:
         elf = json.load(file)

   write_VESTA_format (elf ["AtomInfo"], [elf ["ELF"]["TotalELF"]], "DS-PAW-elf.vesta")

- 第1，2行为需要导入的 **python** 库函数
- 第4，5行为需要读取的 **json** 文件，这里 ``./elf.json`` 指的时读取当前路径下的 ``elf.json`` ，如果需要读取其他的 **json** 文件可以自行修改；
- 第7行为执行 :guilabel:`write_VESTA_format` 函数，将数据保存为 **VESTA** 可识别的格式，其中 **elf["AtomInfo"]** 为读取 ``elf.json`` 中的晶格及坐标信息， **elf ["ELF"]["TotalELF"]** 为读取 ``elf.json`` 中总的局域电荷密度的三维数据, **DS-PAW- elf.vesta** 表示将这些数据写入到 **DS-PAW- elf.vesta** 文件中；

(2) 执行 :guilabel:`python trans_ elf.py` ；
(3) 得到转换后的文件 ``DS-PAW-elf.vesta`` ，将其重命名为 ``elf.vasp`` 以便在 **VESTA** 显示；
(4) 将 ``elf.vasp`` 文件拖入 **VESTA** 中则可得到如下的势能图，展现的效果可以通过设置VESTA中 :guilabel:`Isosurface level` 数值来调节，具体步骤为 **VESTA-properties-Isosurfaces-Isosurface level** 。

.. figure:: images/1-9.png


.. _ 部分电荷密度数据处理:

==============================================================================
pcharge部分电荷密度数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以快速入门石墨烯部分电荷密度计算得到的 ``pcharge.json`` 为例：

(1) 在计算目录中新建一个 :guilabel:`trans_pcharge.py` 文件，内容如下：

.. code-block:: python
  :linenos:

  import json
  from dspawpy.io import write_VESTA_format

  with open("./pcharge.json","r") as file:
        pcharge= json.load(file)

  write_VESTA_format(pcharge["AtomInfo"], [pcharge["Pcharge"][0]["TotalCharge"]], "DS-PAW-pcharge.vesta")


- 第1，2行为需要导入的 **python** 库函数
- 第4，5行为需要读取的 **json** 文件，这里 ``./pcharge.json`` 指的时读取当前路径下的 ``pcharge.json`` ，如果需要读取其他的 **json** 文件可以自行修改；
- 第7行为执行 :guilabel:`write_VESTA_format` 函数，将数据保存为 **VESTA** 可识别的格式，其中 **pcharge["AtomInfo"]** 为读取 ``pcharge.json`` 中的晶格及坐标信息， **pcharge["Pcharge"][0]["TotalCharge"]** 为 ``pcharge.json`` 中第1条待测能带电荷密度的三维数据，此例中为能带4的数据，若写作 **pcharge["Pcharge"][1]["TotalCharge"]** 则读取能带5的数据, **DS-PAW-pcharge.vesta** 表示将这些数据写入到 **DS-PAW-pcharge.vesta** 文件中；

(2) 执行 :guilabel:`python trans_pcharge.py` ；
(3) 得到转换后的文件 ``DS-PAW-pcharge.vesta`` ，将其重命名为 ``pcharge.vasp`` 以便在 **VESTA** 显示；
(4) 将 ``pcharge.vasp`` 文件拖入 **VESTA** 中则可得到如下的势能图，展现的效果可以通过设置vesta中 :guilabel:`Isosurface level` 数值来调节，具体步骤为 **vesta-properties-Isosurfaces-Isosurface level** 。

.. figure:: images/phase2/pcharge-tool.png


.. _ 光学性质数据处理:

==============================================================================
optical光学性质数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以快速入门Si体系光学性质计算得到的 ``optical.json`` 为例：

（1） **反射率数据处理**：

创建 :guilabel:`optical.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  import matplotlib.pyplot as plt
  from dspawpy.plot import plot_optical

  plot_optical("./optical.json","Reflectance",index=0)

  plt.xlabel('Photon energy (eV)', fontsize=16)
  plt.ylabel('Reflectance', fontsize=16)
  plt.tick_params(labelsize=16)

  plt.savefig("optical.png",img_format="png")
  plt.show()

- 第1，2行为需要导入的 **python** 库函数；这里用到了 **matplotlib** 库，以及我们自己写的 **dspawpy.plot** 中的 **plot_optical** 模块
- 第4行调用 **plot_optical** 处理 ``optical.json`` 文件中 **Reflectance** 部分的数据，其中 **Reflectance** 为 ``optical.json`` 文件中的部分数据，这里用户可以根据需要自行修改，若需要处理其他光学性质的数据，可替换该参数为 **AbsorptionCoefficient** 或 **ExtinctionCoefficient** 或 **RefractiveIndex**
- 第6-8行设置x轴y轴的名称以及标签字体大小
- 第9行为保存图片的名称和格式，这里将数据保存为png格式命名为 **optical.png**
- 第10行为显示图片，如果用户运行的环境无法直接显示图片，用户可以将该行注释，之后打开 **optical.png** 文件查看。


.. admonition:: 知识点：

    1. `Reflectance为光学性质中的一种，用户可以根据自己的需求将该关键词修改为“AbsorptionCoefficient”或”ExtinctionCoefficient”或”RefractiveIndex”，分别对应吸收系数、消光系数和折射率；`

执行代码可以得到以下反射率随能量变化的曲线：

.. figure:: images/phase2/optical-Reflectance.png



.. _ 过渡态计算数据处理:

==============================================================================
neb过渡态计算数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以快速入门Pt体系的过渡态计算得到的 ``neb.json`` 为例：

（1） **输入文件之生成中间构型**：

创建 :guilabel:`neb_structure.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from dspawpy.io.structure import from_dspaw_as
  from dspawpy.diffusion.neb import NEB,write_neb_structures

  #导入初态构型
  init_struct = from_dspaw_as("./structure00.as")
  #导入末态构型
  final_struct = from_dspaw_as("./structure06.as")

  #设置插点个数
  neb = NEB(init_struct,final_struct,5)
  structures = neb.idpp_interpolate()

  #修改文件夹存储路径
  write_neb_structures(structures,True,"as","./neb")




.. admonition:: 知识点：

    1. `用户可以根据需要自行修改插点个数，设置为任意插值的序号即可`

执行代码可以得到包含7个结构文件的文件夹，其中新生成的中间构型为5个。

（2） **过渡态计算数据处理**：

创建 :guilabel:`neb.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  import json
  from pymatgen.core import Structure
  from pymatgen.io.vasp import Poscar
  from dspawpy.io.structure import to_file,from_hzw,from_dspaw_as,from_dspaw_atominfo
  from dspawpy.diffusion.neb import NEB,write_neb_structures,plot_neb_barrier,plot_neb_converge
  import matplotlib.pyplot as plt

  plot_neb_barrier("./neb.json")
  plt.xlabel('Reaction Coordinate',fontsize=16)
  plt.ylabel('Energy (eV)',fontsize=16)
  plt.tick_params(labelsize = 16)
  plt.savefig("neb_reaction_coordinate.png",img_format="png")
  plt.show()

  plot_neb_converge("./neb.json","03")
  plt.savefig("neb_ionic_step.png",img_format="png")
  plt.show()

- 第1-6行为需要导入的 **python** 库函数
- 第8行为调用 **plot_neb_barrier** 函数处理 **json** 文件作反应势垒图，这里 **./neb.json** 指的时读取当前路径下的 **neb.json**
- 第9-11行设置x轴y轴的名称以及标签字体大小
- 第12行为保存图片的名称和格式，这里将数据保存为png格式命名为 **neb_reaction_coordinate.png**
- 第13行为显示图片，如果用户运行的环境无法直接显示图片，用户可以将该行注释，之后打开 **neb_reaction_coordinate.png** 文件查看
- 第15行为调用 **plot_neb_converge** 函数处理 **json** 文件作 **03** 构型的弛豫受力图
- 第16行为保存图片的名称和格式
- 第17行为显示图片


.. admonition:: 知识点：

    1. `作能量和力在离子弛豫过程中的变化曲线时，03为处理插入的第3个构型的数据，这里用户可以根据需要自行修改，设置为任意插值的序号即可；`

执行代码可以得到以下能量随反应路径变化曲线：

.. figure:: images/phase2/NEB01.png

.. figure:: images/phase2/NEB02.png


.. _ 声子计算数据处理:

==============================================================================
phonon声子计算数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以Au体系的声子能带态密度计算得到的 ``phonon.json`` 为例：

（1） **声子能带数据处理**：

创建 :guilabel:`phonon_bandplot.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from pymatgen.phonon.plotter import PhononBSPlotter
  from dspawpy.io import get_phonon_band_data

  band_data = get_phonon_band_data("./phonon.json")

  bsp =  PhononBSPlotter(band_data)
  plt = bsp.get_plot()

  plt.savefig("phonon_bandplot.png",img_format="png")
  plt.show()

- 第1、2行为需要导入的 **python** 库函数，这里用到了pymatgen中的 **PhononBSPlotter** 库，以及 :guilabel:`dspawpy.io` 中的 ``get_phonon_band_data`` 函数；
- 第4行为读取 ``phonon.json`` 文件构造 **band_data** 这个结构体；
- 第6行为调用 **PhononBSPlotter** 处理 **band_data** 数据；
- 第7行为使用 ``bsp`` 下的 **get_plot** 进行画图；
- 第9行为保存图片的名称和格式，将数据保存为png格式命名为 **phonon_bandplot.png** ；
- 第10行为显示图片，如果用户运行的环境无法直接显示图片，用户可以将该行注释，之后打开 **phonon_bandplot.png** 文件查看。

执行代码可以得到以下声子能带曲线：

.. figure:: images/phase2/dfpt-Au-band.png

（2） **声子态密度数据处理**：

创建 :guilabel:`phonon_dosplot.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  from pymatgen.phonon.plotter import PhononDosPlotter
  from dspawpy.io import get_phonon_dos_data

  dos = get_phonon_dos_data("phonon.json")

  dp = PhononDosPlotter()
  dp.add_dos("Phonon",dos)
  plt = dp.get_plot()

  plt.savefig("phonon_dosplot.png",img_format="png")
  plt.show()


执行代码可以得到以下声子态密度曲线：

.. figure:: images/phase2/dfpt-Au-dos.png


.. _ 分子动力学模拟数据处理:

==============================================================================
aimd分子动力学模拟数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以快速入门 :math:`H_{2}O`  分子体系分子动力学模拟得到的 ``aimd.json`` 为例：

（1） **分子动力学模拟数据处理**：

创建 :guilabel:`aimd2pdb.py` 文件，具体代码如下：

.. code-block:: python
  :linenos:

  import json
  from dspawpy.io.structure import from_dspaw_atominfos,to_pdb

  with open("./aimd.json","r") as file:
      aimd = json.load(file)

  structures = from_dspaw_atominfos(aimd["Structures"])
  to_pdb(structures,"aimd.pdb")

- 第1，2行为需要导入的 **python** 库函数

- 第4，5行为需要读取的 **json** 文件，这里 **./aimd.json** 指的是读取当前路径下的 **aimd.json** ，如果需要读取其他的 **json** 文件可以自行修改

- 第7行为调用 :guilabel:`from_dspaw_atominfos` 处理 **structure** 的数据

- 第8行将处理的数据转为 **pdb** 格式


执行代码可以得到包含体系原子径向分布信息的文件 :guilabel:`aimd.pdb` ，得到通用轨迹pdb文件后，就可以利用vmd等分子动力学后处理软件进行分析。
例如VMD中处理RDFs操作步骤：File - New Molecule - browse - open - Load - Extensions - Analysis - Radial Pair Distribution Function g(r) -
Selection 1: element H , selction 2: element O - compute g(r)